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Abstract This paper contains details on the algorithms implemented in the TEMP02 
pulsar timing software package and describes how the software is used. Information is 
given on how to download and install the software, use the various interfaces, simulate 
realistic data sets and develop the software. The use of TEMP02 in predictive mode is 
also described. 
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1 INTRODUCTION 

The Tempo2 software package was first released in the year 2006. It is based on the original TEMPO 
software 1 (hereafter called TEMPO 1) and implements pulsar timing algorithms with a precision and 
accuracy of ~1 ns. Tempo2 has already been used for numerous applications including: determining 
the mass of the Jovian system' 1 ', providing the first evidence for ion-neutral damping in the interstel- 
lar medium' 21 , developing an ensemble pulsar time scale, studying radio pulses from a main-sequence 
star' 3 ', multi-telescope observations of various pulsars' 4,51 and studies of pulsar glitch events' 61 . 

Usually TEMP02 is used to compare a model for a pulsar's rotation, position and orbital parameters 
with actual observations of pulse arrival times. The difference between actual and predicted arrival times 
are known as the pulsar "timing residuals". After calculating these timing residuals, TEMP02 carries out 
a linear least-squares-fit to improve the parameters in the model. It is possible that the model is too 
simplistic and does not contain all the phenomena that affect the pulse arrival times. For instance, the 
pulsar may undergo glitch events, or may have unmodelled binary companions. Various tools exist to 
study such effects that are not included in the timing model. Tempo2 can also be used to predict the 
pulse period and phase at any given time. This is commonly used for online systems that need to "fold" 
the incoming data at the predicted topocentric period of the pulsar. 

The algorithms are described in brief in the sections below and detailed in the three major TEMP02 
publications: Hobbs, Edwards & Manchester (2006)' 7 ', Edwards, Hobbs & Manchester (2006)' 8] and 
Hobbs et al. (2008)' 9 '. Here we provide an example of the TEMP02 software in use (Section 2), provide 
an overview of the algorithms (Section 3), details for using and developing the software (Sections 4 and 
5) and some important points to note when published results (Section 6). 

2 EXAMPLE USAGE OF TEMP02 

In this section we provide an overview of how TEMP02 is used. For this demonstration we use observa- 
tions from the Parkes Observatory. Our procedure for obtaining observations to process is as follows: 

- Obtain pre-processed data files from the Parkes data archive. This is described by Khoo (these 
proceedings) and in Hobbs et al. (201 1)' 10 '. Note: for the following example 34 observations were 
used. 



see, e.g., http : / /www . atnf . csiro . au /research/pulsar /tempo 
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- Create an analytic standard template from the highest S/N observation: 

% paas -Ci f 4 4 5_1 7 5214 . FTp 

- Obtain pulse times of arrival using 

% pat -s paas . std -f tempo2 *.FTp > J1539.tim 

An initial timing model is needed. This can be obtained from the ATNF Pulsar Catalogue^ 111 2 
by typing in the pulsar's name (J1539— 5626 for our example) into the "Pulsar names" box and 
clicking on "Get Ephemeris". The output ephemeris was copied into a text file called J1539.par. 

Tempo2 can be run by typing: 

% tempo2 -f J1539.par J1539.tim 
The output is as follows: 

Results for PSR J1539-5626 

RMS pre-fit residual = 61071.224 (us), RMS post-fit residual = 61071.224 (us) 
Number of points in fit = 34 



PARAMETER 


Pre-fit 


Post- 


fit 


Uncertainty 


Difference 


Fit 


RAJ (rad) 


4 .09817561890493 


4.098 


17561890493 








N 


RAJ (hms) 


15:39:13.96 


15:39 


: 13. 96 










DECJ (rad) 


-0 . 985070617217135 


-0 . 98 


5070617217135 








N 


DECJ (dms) 


-56 : 26 : 25 . 4 


-56:26:25.4 










FO (s"-l) 


4 .108595092 


4 .108 


595092 








N 


Fl (s"-2) 


-8 . 1859e-14 


-8 . 1859e-14 








N 


PEPOCH (MJD) 


48376 


48376 










N 


POSEPOCH (MJD) 


48376 


48376 










N 


DMEPOCH (MJD) 


48376 


48376 










N 


DM (cm" -3 pc) 


175 .88 


175 . 8 


8 








K 


START (MJD) 





51021 


. 3077195533 





51021 


N 


FINISH (MJD) 





54144 


. 03803532 





54144 


N 


TZRMJD 





52458 


. 4201897289 





52458 


N 


TZRFRQ (MHz) 





1374 







1374 


N 


TZRSITE 


7 












TRES 





61071 


. 2244943135 





61071 


N 


EPHVER 


2 


2 










N 



Derived parameters : 

P0 (s) = 0.243392200401334 

PI = 4 . 84930777711516e-15 

tau_c (Myr) = 0.79578 
bs (G) = 1.0994e+12 

Total time span = 3122.728 days = 8.550 years 
Finishing off: time taken = 1.82 (s) 

This output provides the pre- and post-fit timing residuals (and, for a weighted fit, the reduced-;^ 2 
of the fit) and the number of observations included in the fit. For this example, the pre- and post-fit 
timing residuals are identical as no fit was carried out. For each parameter in the timing model, the 
output contains its name, pre- and post-fit parameter values, the uncertainty of the fitted value and the 
size of the change in the parameter. Various derived parameters are listed including the pulse period and 



2 http : / /www .atnf.csiro. au/ research/pulsar /psrcat 
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its derivative, the pulsar's characteristic age and surface magnetic field strength (all calculated from the 
pulse frequency and its derivative). The final text in the output gives the total data span and the time 
taken for the TEMP02 software to run. 

It is also possible to view the results interactively. Typing 

% tempo2 -gr plk -f J1539.par J1539.tim 

produces the output shown in the top-left panel of Figure 1 (Note: that white and black has been reversed 
for these figures). The small points in the centre of each panel are the "timing residuals". A group of 
observations have been circled (by clicking on them with the middle mouse button). These particular 
observations are, for an unknown reason, corrupted and should be deleted (by clicking on them with 
the right mouse button). Once these points have been removed a new arrival-time file can be created by 
clicking on "New tim" and typing "tempo2" followed by the new filename (J15 3 9_2 . tim). 

Note from the top-left panel in Figure 1 that the residuals have a large offset of one pulse period 
near the centre of the plot. This is known as a "phase wrap" (described in Section 3.6). The phase jump 
can be removed by positioning the mouse cursor at the time of the phase jump and pressing '+'. The 
resulting plot is shown in the top-right panel of the figure. The main feature of this panel is the linear 
trend seen in the timing residuals. This occurs because the pulse frequency in the ephemeris is not 
precise. We can update the model for the pulse frequency and its time derivative by selecting the "FO" 
and "Fl" buttons seen at the top of the page (or, as described above, by placing a ' 1 ' in the timing model 
file after the parameter value) and then clicking on the "RE -F I T" button. In the bottom-left panel of the 
figure, we show the resulting plot after selecting to plot the "post-fit" timing residuals on the y-axis 
(after fitting, the phase jump can be removed by pressing the "Backspace", or "delete", key). The 
post-fit pulsar timing model can be saved by clicking on "New par" and typing in the name of the new 
parameter file (here we use J1539_2 .par). 

The resulting timing residuals shown in the bottom-left panel of Figure 1 are caused by 1) pulsar 
timing noise' 12 ' and references therein) and 2) an inaccurate estimate of the pulsar's position in the 
timing model. As described in Coles et al. (201 1) [13] , it is not correct simply to fit for the pulsar's 
position in the presence of non-white timing residuals. Using the methods described in the Coles et 
al. paper it is possible to determine an improved position using these data. Putting these values into a 
new parameter file J1539_3.par leads to the timing residuals shown in the bottom-right panel in the 
figure. 

3 OVERVIEW OF ALGORITHMS 

In this section we provide an overview of the algorithms implemented in TEMP02. Mathematical details 
are provided in Edwards, Hobbs & Manchester (2006) [8] . In brief, the pulse arrival times at the Solar 
System barycentre are determined. These barycentric arrival times are compared with predicted arrival 
times given the pulsar timing model to form pulsar timing residuals. A least-squares-fitting procedure 
is carried out to improve the pulsar timing model and the entire process iterated to form post-fit timing 
residuals. 

3.1 Clock corrections and Einstein delay 

Pulse times-of-arrival (TOAs) are measured relative to the observatory time standard (such time stan- 
dards are usually based on a hydrogen maser providing a stable reference frequency) and the Global 
Positioning System (GPS) satellites to refer the TOAs to international time standards. Observatory 
time standards are usually relatively unstable over timescales of months to years. It is therefore es- 
sential to convert the measured pulse TOAs to a realisation of Terrestrial Time (TT). For most purposes, 
International Atomic Time (TAI) is an adequate realisation of terrestrial time, TT(TAI). However, for 
high precision pulsar timing observations, the post-corrected time standard published by the Bureau 
International des Poids et Mesures (BIPM) may be necessary. 
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Fig. 1 Example PSR J1539— 5626 data set. Each panel in this figure was made using the PLK interface 
to TEMP02. The top-left panel contains the timing residuals obtained using the ephemeris in the ATNF 
pulsar catalogue. The top-right panel shows the residuals after removing the phase-wrap. The bottom- 
left panel shows post-fit residuals after fitting for the pulse frequency and its first time derivative. The 
bottom-right panel shows the final fit, which included a fit for the pulsar's position. 



Tempo2 converts the recorded TOAs to a requested realisation of TT via a set of clock correc- 
tions. These clock corrections are given in various text files that contain the difference between two 
time standards and the date of the measurement. For instance, to correct observations from the Parkes 
Observatory, the pks2gps . elk, gps2utc . elk, utc2tai . elk and tai2tt_tai files are used. 
For our example data set (used in Section 2), the time corrections from the observatory to terrestrial time 
range from ~ 63 to 65 seconds. This correction arises from an original 32.184 s offset between TAI and 
TT, plus leap-second compensation from UTC to TAI (currently 34 s). The conversion from the Parkes 
observatory time standard to the GPS standard is typically ~1 /is and the conversion from GPS to UTC 
is ~ 10 ns. 

After conversion to a realisation of TT, it is necessary to make the relativistic conversion of the TOAs 
to the frame of the Solar System barycentre. This is undertaken within TEMP02 using the tabulated 
results of Irwin & Fukushima (1999) [141 . The size of this conversion is typically a few milliseconds. 
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3.2 Roemer delay 

The Roemer delay, A r , is the geometric time delay between the pulse arriving at the observatory and 
when the pulse passes the Solar System barycentre. For a unit vector, k, pointing from the Earth to the 
pulsar (assumed to be the same from the barycentre), 

R ■ k 

A r = (1) 

c 

where c is the vacuum speed of light and R is the vector from the observatory to the barycentre. R is 
calculated by determining the 1) vector from the observatory to the Earth's centre (obtained from a data 
file containing the geocentric coordinates of each observatory) and 2) vector from the Earth's centre to 
the barycentre (obtained from a Solar System planetary ephemeris). By default TEMP02 uses the DE405 
JPL Solar System planetary ephemeris, but modern precision timing experiments are now making use 
ofDE414or DE421. 

3.3 Shapiro delay 

The Solar System Shapiro delay' 151 is the time delay caused by the passage of the pulse through gravita- 
tional fields in the Solar System. Tempo2 includes the delay caused by the Sun (in which the delay, for 
a line-of-sight passing the limb of the Sun, is < 110/is), Jupiter (< 180 ns), Saturn (< 58 ns), Neptune 
(< 12ns) and Uranus (< 10ns). 

For pulsars with a companion, TEMP02 can also include the effect of the gravitational time delay in 
the vicinity of the companion (the orbital Shapiro delay); see Section 3.5. 

3.4 Dispersive delays 

The pulse TOAs are affected by dispersion in the interstellar medium and in the interplanetary medium. 
The interstellar dispersion delay is included in TEMP02 using the standard relation: 

A ISM = JjSwy W 

where D is the dispersion constant and / SSB is the frequency of the radiation at the SSB. The dispersion 
constant is related to the "dispersion measure" (DM) as DM = 2.410 x 10 _16 Dcm _3 pc. By default, 
TEMP02 uses a very simple, spherical model of the Solar Wind to approximate the interplanetary dis- 
persion. You et al. (2007) [16] have implemented a more detailed mode that requires on observations from 
the Wilcox Solar observatory 3 . 

3.5 Orbital motion 

The binary model used by TEMP02 is based on those of Blandford & Teukolsky (1976)' 171 , Damour 
& Deruelle (1985) [18] , Taylor & Weisberg (1989) [19] with extra terms as described by Kopeikin (1995, 
1996) [20 ' 21] . The binary model accounts for the variation in the distance of the pulsar due to the orbital 
motion, the aberration of the radio beam and the orbital Einstein and Shapiro delays. 

For most binary pulsars, the five Keplerian parameters (the binary period, orbital eccentricity, pro- 
jected semi-major axis of orbit, epoch of periastron and the longitude of periastron) are sufficient to 
parameterise the orbit. In some cases, post-Keplerian parameters (such as the periastron advance) are 
required. A list of the possible binary parameters is given in Table 7 of Hobbs, Edwards & Manchester 
(2006) [7] . 



3 http://wso.stanford.edu/ 
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3.6 Forming residuals and the fitting algorithm 

The delays described in the sections above allow the determination of barycentric arrival times. The 
time-evolution of the pulse phase, (f>, is determined based on the model of the pulse frequency {v) and 
its derivatives: 



1 . 1 



4> = (po + vt + -vt + -vt 2 + ... (3) 
2 o 

where k is the number of frequency derivatives and t is the pulse emission time in the reference frame 
centred on the pulsar. 

The timing residual for the i'th observation is determined from: 

4>(ti) - Ni 

Ri = — (4) 

v 

where N t is the nearest integer to the value of <f> at the time of the observation, <j){ti). Note that if the 
pulse arrived earlier than expected, the resulting residual will be negative. 

If the model parameter estimates are sufficiently poor that the difference between the predicted 
arrival time and the actual arrival times becomes greater than half the period of the pulsar then a "phase 
wrap" will occur (as demonstrated in Figure 1). 

A linear least-squares-fitting procedure is used to improve the parameter estimates. These new val- 
ues can subsequently be used to determine post-fit timing residuals. Usually, this least-squares-fitting 
procedure accounts for the different arrival time uncertainties between different observations (i.e., it is 
a weighted fit). However, if required, it is possible for the user to request an unweighted fit. 



4 USING THE SOFTWARE 

4.1 Downloading and installing the software 

The main TEMP02 webpage, http://www.atnf.csiro.au/research/pulsar/tempo2, 
provides up-to-date details on downloading and installing the software. Tempo2 has been installed 
on both MacOS X and LINUX operating systems. It has been tested with recent versions of gcc, g++ 
and gf ortran. It is also highly recommended that pgplot be installed before compiling TEMP02. 
The most common problems that occur during installation are: 

- having different versions of gcc, g++ and gf ortran. The versions of these packages can be de- 
termined using gcc -v, g++ -v and gf ortran -v. Also ensure that your version of pgplot 
has been installed using the same version of gf ortran. 

- not setting the $TEMP02 environment variable. Setting of this variable is described in the docu- 
mentation for installing the software. 

- not installing the plugin packages. It is necessary to type make install to ensure that all the 
plugin packages are copied to the correct directory. 

In order to test your installation, type: 

% tempo2 -h 

which should provide general information about the software. 



4.2 Required data files 

Tempo2 requires a set of files to run correctly. The most up-to-date versions of these files are part of the 
standard TEMP02 distribution, but it may become necessary to update these files. All the files are stored 
in a directory structure that is defined by the $TEMP02 environment variable. The most important files 
are within the following sub-directories: 
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- clock: each file has the extension .elk and contains the time transfer corrections from one time 
standard to another. For instance, the file pks2gps . elk contains the corrections from the Parkes 
observatory to the global positioning system satellites time standard. New clock files may be added 
to this directory as required (for instance, from a new telescope time standard to a realisation of 
terrestrial time). 

- earth: This directory contains a single file that contains the Earth orientation parameters as pro- 
vides by the International Earth Rotation and Reference Systems Service. 

- ephemeris: Each file contains a planetary ephemeris necessary for determining the position and 
velocity of the Solar System objects. 

- observatory: The file observatories . dat contains the geocentric coordinates of all the 
telescopes that can be used in TEMP02. New telescopes may be added as required. 

4.2.1 Parameter files 

Tempo2 always requires a model for the pulsar's spin, astrometric, dispersion measure and, for binary 
systems, orbital parameters. This model is included in a single file with at least two columns. The first 
column contains a label for each parameter and the second column contains the parameter value. All 
parameter files are required to contain the pulsar's name (PSRJ), its right ascension (RAJ), declina- 
tion (DECJ), a pulse-frequency (FO), dispersion measure (DM) and the epoch of the pulse-frequency 
measurement (PEPOCH) 4 . An example is shown below: 



PSRJ J1539-5626 

RAJ 15:39:14.0643716 

DECJ -56:26:26.28676 

FO 4.1085950845961150884 1 4e-10 

PEPOCH 48376 

DM 17 5.88 



The third column for the pulse frequency (F 0) row is used to request that TEMP02 fits for this parameter 
(the '1' in column 3). The fourth column gives the uncertainty on the parameter (4 x 1CP 10 ). Neither of 
these last two columns are required. 

Various other parameters are often included such as the pulse-frequency derivative (Fl), orbital 
parameters or definitions of the clock files to use. 

Tempo2 parameter files are identified with EPHVER 5 included in the parameter file. Following 
the IAU resolution A4 (1991), the TEMP02 algorithms make use of barycentric coordinate time (TCB). 
Pulsar timing models obtained using TEMPOl made use of barycentric dynamical time (TDB). The 
conversion from TDB parameter file to TCB is described in Hobbs, Edwards & Manchester (2006)' 7] 
and can be carried out by typing 5 : 

% tempo2 -gr transform oldfile.par newfile.par 
The output file (newf ile . par) will be compatible with TEMP02. 
4.2.2 Arrival time files 

Arrival time files contain the pulse arrival times and related information for each observation. The start 
of a typical arrival time file is shown below for Parkes observations. 



4 It is possible to provide ecliptic coordinates (ELONG, ELAT) instead of RAJ and DECJ, or the pulse period (PO) instead of 
the frequency (FO). 

5 TEMP02 can automatically carry out this conversion if the parameter EPHVER 2 is included in the parameter file. However, 
we recommend converting all parameter files to be consistent with TCB. 
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FORMAT 1 

filel 1405.0 52618.5056325016767 0.236 PKS -r MULT I -b CPSR2 
file2 660.89 52742.3494510752533 1.209 PKS -r 50CM -b CPSR2 
file3 1431.028 53143.0195601772366 0.109 PKS -r H-OH -b WBCORR 

The first line of the file (FORMAT 1) indicates that this file is in the standard TEMP02 format (note, 
it is possible to read earlier TEMPO 1 -style files, if necessary). Each subsequent line corresponds to a 
pulse site-arrival-time. The first five columns are required for all observations and contain the file name 
or identifier, the observing frequency (MHz), the pulse site-arrival-time (MJD), the uncertainty on the 
arrival time (/is) and the observing site. In the example above, we have also included two "flags" that 
represent the receiver used (given by the "-r" flag) and the observing backend system (the "-b" flag). 
Such flags are not necessary, but can be very useful in subsequent processing to identify observations of 
interest. The choice of flag labels (here "-r" and "-b") can be chosen by the user 6 . 

4.3 Getting help 

There are various ways to learn how to use the TEMP02 software. For most interfaces it is possible 
simply to type -h on the command-line to obtain basic usage information, for instance typing: 

% tempo2 -h 

will describe the main TEMP02 code, whereas: 

% tempo2 -gr plk -h 

will describe the plk graphical interface (see Section 4.4.1). The main TEMP02 website provides doc- 
umentation on many aspects of the software. However, the webpage also contains tutorials that provide 
step-by-step instructions on how to do a particular task (such as fitting for pulsar parameters in the pres- 
ence of pulsar timing noise). Many of the graphical plugin-packages provide interactive help. This is 
usually accessed by pressing 'h'. 

General discussion on the use of TEMP02 and reports on issues within the software are 
emailed to the TEMP02 email distribution list. This list is publically available from http:// 
pulsar astronomy .net. 

4.4 The graphical interfaces 

The TEMP02 functionality can be enhanced using "plugin-packages" (or "interfaces"). These interfaces 
can be used to provide different textual output (the "output" interfaces; section 4.6) or to provide inter- 
active, graphical interfaces 7 . In the subsequent sections we describe some of the most commonly-used 
interfaces. 

4.4.1 plk 

The most common graphical interface is PLK which provides an interactive interface for viewing and 
processing the pre- and post-fit timing residuals. Figure 1 shows a typical example. By default all obser- 
vations in the 50 cm observing band are displayed in red, those at 20 cm in green and around 10 cm in 
blue. The user may select different bands or colours as required (see below). 

The plugin provides a large number of options that can be obtained by pressing various keys. The 
most common are listed in Table 1 . There are also a set of command-line arguments that may be used: 

6 There are a few flag labels, such as "-dm" that have particular meaning to TEMP02. These are described in the standard 
TEMP02 documentation. 

7 It is also possible to use interfaces to control the selection of data for analysis (the -splug interfaces) and for changing the 
fitting algorithms within TEMP02 (the -f itfunc interfaces). These interfaces are not discussed in this paper. 
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% tempo2 -gr plk -f J1539.par J1539.tim -us 

will plot the residuals in microseconds (note: -ns and -ms may also be used to plot in nanoseconds 
and milliseconds respectively). 

% tempo2 -gr plk -f J1539.par J1539.tim -publish 

selects a suitable colour scheme for making publication quality plots. 

In order to modify the colours and fonts, a new file can be created that is similar to the 
$TEMP02 /plugin_data/plk_setup_data . dat file. The file can be stored in the local direc- 
tory and is accessed using: 

% tempo2 -gr plk -f J1539.par J1539.tim -setup mysetupfile.dat 
The available options for setup files are listed in Table 2. 

Table 1 Commands Available For the "plk" Interface 



Key 


Meaning 


1 


plot pre-fit residuals versus date 


2 


plot post-fit residuals versus date 


3 


plot pre-fit residuals versus orbital phase 


4 


plot post-fit residuals versus orbital phase 


5 


plot pre-fit residuals serially 


6 


plot post-fit residuals serially 


7 


plot pre-fit residuals versus day of year 


8 


plot post-fit residuals versus day of year 


9 


plot pre-fit residuals versus frequency 


a 


plot post-fit residuals versus frequency 


+ 


Add phase wrap at mouse position 




Subtract phase wrap at mouse position 


Backspace 


Remove all phase wraps 


g 


Change graphics device 


h 


Display 'help' information 


H 


Highlight observations based on a flag value 


1 


List all points in region 


o 


Highlight all observations in selection region 


N 


Highlight observation based on its filename 


w 


Toggle fitting with weights 


X 


Re-do the fit 


z 


Select a group of observations using the mouse 


Z 


Delete a group of observations selected using the mouse 


ctrl-d 


delete all selected observations 


ctrl-i 


Highlight observations based on their flag values 


ctrl-r 


Create a region file for use with the glitch plugin (see Section 4.4.2) 


ctrl-s 


Overwrite arrival time file 


ctrl-w 


Overwrite parameter file with new values 


middle mouse 


Display profile if PSRCHIVE" installed 


right mouse 


Delete closest observation 


left mouse 


Display information about closest observation 



a http://psrchive.sourceforge.net 1 



4.4.2 glitch 

The GLITCH plugin allows glitch events to be analysed and identified. This plugin requires the input of 
a set of parameter and arrival time files that provide coherent timing solutions of specified time intervals 
These can be obtained by creating a "region" file using the PLK plugin. Within PLK the user first presses 
'ctrl-r' and then uses the left mouse button to indicate data spans which include a sufficient number of 
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Table 2 Commands Allowed in a Setup File for the PLK Interface 



Key Meaning 

aspect Aspect ratio (default = 0.8) 

background Colour of background (default = "black") 

f req <f lo fhi col style> Definition of symbol and colour for a given frequency range. 

The first two parameters give the frequency range (MHz). The 
remaining two parameters give the PGPLOT colour and point- 
style. 

font size Size of font (default = 1.0) 

f onttype Font PGPLOT-style (default = 1) 

line Colour of foreground lines (default = "white") 

linewidth Line width (default = 1.0) 

menu Initial menu display (use for no menu) 



J1709-4429 




< 



3000 4000 5000 

Days after MJD 47700 



Fig. 2 Glitch events in PSR J1709— 4429. Figure from Yu, M. (personal communication) using the 
GLITCH plugin to TEMP02. Each vertical, dotted line indicates the epoch of a glitch. The top panel 
shows the pulse-frequency as a function of time. The second panel shows the same, but after a mean 
has been subtracted between each glitch event. The bottom panel shows the time variation of the pulse- 
frequency derivative. 



observations to determine the pulse frequency and, if required, its derivative. The right mouse button is 
clicked to complete this process and to create the "region" file. 

For each time interval in the "region" file, the glitch plugin determines the pulse frequency and, if 
requested, its first time derivative. These values can subsequently be plotted (an example is shown in 
Figure 2). Such figures can be used to estimate the time and size of each glitch. These estimates can 
subsequently be included in the pulsar's timing model and a standard TEMP02 fit can be used to obtain 
improved estimates. 
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4.4.3 plotMany and splk 

In contrast to TEMPO 1, the TEMP02 software can process multiple pulsars simultaneously. Extra pulsar 
data sets are added to the command line using multiple -f arguments. For instance, 

% tempo2 -gr plotMany -f psrl.par psrl.tim -f psr2.par psr2.tim 
-f psr3.par psr3.tim 

will obtain post-fit timing residuals for all three pulsar data sets. An example of the output from the 
plotMany plugin is shown in Figure 3. 

If only a few pulsars are being analysed then the SPLK interface can be used. This interface allows 
their pre- and post-fit residuals to be displayed using the same scaling (either in separate panels or 
overlaid in one figure). 

New algorithms are being developed that allow fits to be applied globally over many pulsars. For 
instance, Hobbs et al. (2010) [23] reported on determining errors in the terrestrial time standard by fitting 
for the correlated signal within each pulsar's data set. 

4.4.4 Spectrum 

In order to understand the post-fit timing residuals it is often necessary to obtain a power spectrum of 
the residuals. This is not trivial because most pulsar data sets are unevenly sampled. The SPECTRUM 
plugin implements various algorithms for determining a power spectrum (including the Lomb-Scargle 
periodogram and a weighted fit of harmonically related sinusoids). In Figure 4 we show the output from: 

% tempo2 -gr spectrum -f 0437. par 0437. tim 

where the input data set was taken from Verbiest et al. (2008) [25] . 

4.5 Fermi 

The FERMI plugin allows the user to determine a pulse phase for each photon arrival time in a Fermi 
Large Area Telescope (Fermi) event file. Documentation and usage instructions for this plugin are avail- 
able from the Fermi website 8 . 

4.6 The Output interfaces 

For the output interfaces, the TEMP02 software runs as normal, but, instead of producing the default 
output, allows the interface to report the results in a manner that is suitable for a particular application. 

4.6.7 General 

The general interface provides a generalised method for displaying the post-fit pulsar timing param- 
eters. This interface can be used to produce output suitable for parsing with other software packages. 
For instance, 

% tempo2 -output general -s " { ALL_1 } & { ALL_p } WW \n" 
-f mypar.par mytim.tim 

will produce output that is suitable for inclusion as a table in a KTgX document. If the only parameters 
of interest are the pulse frequency and dispersion measure then the following can be used: 

% tempo2 -output general -s "Pulse frequency = {F0_v} \nDispersion 
measure = {DM_v}\n" -f mypar.par mytim.tim 

A list of the most commonly used commands is given in Table 3. 

8 f ermi .gsfc.nasa. gov/ssc/data/ana lysis /user /Fermi_plug_doc . pdf 
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Fig. 3 Example of the PLOTMANY plugin that shows the post-fit timing residuals for multiple pulsars. 
These data were published by Verbiest et al. (2009) [241 .The value under each pulsar name gives the range 
from the minimum to the maximum residual. 



4.6.2 General2 

As described in Section 3, TEMP02 determines a large number of time delays that need to be applied 
to the observed site-arrival-times before the timing residuals are calculated. The general2 interface 
provides access to all the delays that are calculated and the various parameters required in the algorithms 
for each observation. For instance, 

% tempo2 -output general2 -s "{sat} {bat} {freq} {ism} {roemer} 
{shapiro}\n" -f mypar.par mytim.tim > outfile.txt 

lists, for each observation, the site arrival time, barycentric arrival time, observing frequency, and the 
delays due to the interstellar medium, the Roemer delay and the Solar System Shapiro delay. In the 
above example, the output is stored in a file out file . txt that can subsequently be loaded into other 
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Frequency (yr 1 ) 



Fig.4 Lomb-Scargle power spectrum of the post-fit timing residuals for PSR J0437— 4715 obtained 
using the SPECTRUM plugin. 



Table 3 Commands Available For the "general" Interface 



Parameter 


Meaning 


ALL_1 


List the labels of all parameters in a column 


ALL_V 


List the values of all the parameters in a column 


ALL_e 


List the parameter uncertainties in a column 


ALL_p 


Use publication format for displaying parameter uncertainties 


F0_p 


List the FO parameter" 


F0_1 


Display the label for the FO parameter" 


F0_e 


Display the uncertainty for the FO parameter" 


F0_p 


Display the uncertainty for the FO parameter in publication mode" 


name 


Pulsar's name 


nobs 


Number of observations 


postrms 


Rms of the post-fit timing residuals (s) 


prerms 


Rms of the pre-fit timing residuals (s) 


tspan 


Data span (d) 



" can also be used for any other parameter (e.g., RAJ_v, DM_e) 



software packages (such as gnuplot, mat lab, idl, etc.). A list of the commonly used parameters 
that can be used with the general2 interface are given in Table 4. 

4.7 Simulating data 

Data can be simulated for numerous purposes included 1) creating test data sets to trial TEMP02 or other 
programs, or 2) producing realistic simulations for use in Monte-Carlo simulations. 

The fake graphical interface provides an easy method for simulating simple data sets. For instance, 
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Table 4 Most Common Commands Available with the "general2" Interface 



Parameter 



Meaning 



file 

f req 

ipm 

ism 

pre 

post 

roemer 

sat 

shapiro 

Shapiro J 

solarangle 

tropo 

tt 

tt2tb 



bat 

clockO, clockl, 



earth_ssbl 
earth_ssb2 
earth_ssb3 
err 



barycentric arrival time 

The various clock corrections (s) 

X-coordinate of distance to Solar System Barycentre from Earth (lt-s) 

Y-coordinate of distance to Solar System Barycentre from Earth (lt-s) 

Z-coordinate of distance to Solar System Barycentre from Earth (lt-s) 

Time of arrival uncertainty (/is) 

identification of pulsar observation (usually filename) 

observing frequency (MHz) 

Delay caused by the interplanetary medium (s) 

Delay caused by the interstellar medium (s) 

Pre-fit timing residual (s) 

Post-fit timing residual (s) 

Roemer delay (s) 

site arrival time 

Shapiro delay caused by Sun (s) 

Shapiro delay caused by Jupiter (s) 

Angle between the Observatory, pulsar and Sun (deg) 

Tropospheric delay (s) 

Correction from observatory time standard to Terrestrial Time (s) 
Correction from Terrestrial Time to Barycentric Time (s) 



% tempo2 -gr fake -f 1534_3.par -ndobs 14 -nobsd 1 -randha y -ha 8 
-rms le-3 -start 51000 -end 54000 

will simulate regularly sampled data from MJD 51000 to 54000 with one observation (-nobsd 1) ev- 
ery 14 days (-ndobs 14). The time of each observation will be based upon the pulsar's transit time. An 
assumed hour angle range of 8 hours (-ha 8) is used and a random hour angle chosen (-randha y). 
Each arrival time has an uncertainty of 1 /is (-rms le-3). One realisation of such timing residu- 
als is shown in the left-hand panel of Figure 5. The resulting arrival times are stored in a file called 
J1539_3 . simulate. 

Note that the fake interface can simulate data for numerous pulsars: 

% tempo2 -gr fake -f myparl.par mypar2.par mypar3.par ... 

For non-regularly sampled data, it is possible to provide a list of MJDs (e.g., in a file called 

mytimes . dat): 

% tempo2 -gr fake -times mytimes.dat ... 

Tempo2 also provides numerous methods for simulating the induced timing residuals caused by 
gravitational waves. The GWBKGRD plugin may be used to simulate the effect of an isotropic, stochastic 
background of gravitational waves' 121 . The timing residuals for one realisation of such a background is 
shown in the right-hand panel of Figure 5 and can be obtained using: 

% tempo2 -gr GWbkgrd -f J1539_3.par J1539_3 . simulate -alpha -0.666 
-dist 1 -gwamp le-13 -ngw 10000 

where -gwamp gives the dimensionless amplitude of the gravitational wave background, -alpha is 
the spectral exponent of the background, -dist the pulsar's distance in kpc and -ngw the number of 
gravitational wave sources to simulate. 

4.8 TEMP02 and predictive mode 

There are many applications that require knowledge of a pulsar's pulse phase or frequency at a specified 
time (or over a particular time interval). For instance, when carrying out observations of pulsars it is 
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J1539-5626 (rms = 1.007 fjs) pre-fit 




MJD-52501.4 
J1539-5626 (rms = 3.929 /xs) post-fit 




-1000 1000 



MJD-52501.4 

Fig. 5 Simulated data sets. The left panel contains simulated white noise produced using the FAKE plu- 
gin. The right panel shows the timing residuals induced by a simulated gravitational wave background 
obtained using the GWBKGRD plugin. 



common to "fold" the incoming data stream at the known pulse frequency. For such applications both 
TEMPO 1 and TEMP02 provide a polynomial approximation of the topocentric phase and frequency over 
specified time intervals. The number of polynomial coefficients and the time-span to be fitted are defined 
by the user. 

TempoI produced "polycos" that are specific to a given observing frequency. For compat- 
ibility with older systems, Tempo2 can produce polycos, but we instead recommend the use of 
"predictors". The two types are similar, but predictors are based on Chebyshev polynomials 
and are both time- and frequency-dependent 9 . 



9 Section 7.1 in Hobbs, Edwards & Mancheser 2006 provide more details of why a frequency-dependent prediction is neces- 
sary for high-precision observations of binary pulsars 
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A predictor can be produced using: 

% tempo2 -f mypar.par -pred "sitename mjdl mjd2 freql freq2 
ntimecoeff nfreqcoeff seg_length" 

(note: use of quote marks around the arguments for the predictor). Here sitename is the code 
for the observatory (see Section 4.2), mjdl and mjd2 give the time range for the predictor, freql 
and f req2 give the frequency range (in MHz), ntimecoeff and nfreqcoeff give the number of 
time and frequency coefficients respectively and seg_length gives the duration of each segment (in 
seconds). For instance, 

% tempo2 -f J1539_2.par -pred "PKS 53000 53000.1 1400 1420 12 2 3600" 
produces a file, t2pred . dat, that contains three segments. The first of which is: 

ChebyModelSet 3 segments 
ChebyModel BEGIN 
PSRNAME J1539-5626 
SITENAME PKS 

TIME_RANGE 53000 53000.04166666666666785090455960017 
FREQ_RANGE 1400 1420 

DISPERSION_CONSTANT -2 998630.668904615781912070815451443 
NCOEFF_TIME 12 
NCOEFF„FREQ 2 

COEFFS 769018109. 217955444648396223783493 3.686485191186269124433103496556908e-10 
COEFFS 14791. 39113118368792765267016875441 -2.714781880778597648478063579182172e-09 
COEFFS -0. 0002377901740449791153227876701965922 2.400943518688284986653565320064977e-ll 
COEFFS 2. 098262484651058912277221679687 5e-06 1. 38911732152604722151309423155800 3e-10 
COEFFS 1. 20734815330555041626754593163786 3e-07 -1.183322162781448724601720341887527e-10 
COEFFS 6. 03904481977224349975585937 5e-10 -3. 94440720 92 7149548982084277310375e- 11 
COEFFS -3.443953270713488260820802753443092e-10 -8.917790212265989797173902108842651e-ll 
COEFFS 8. 07631295174360275268554687 5e-10 -1. 972203 604 6357477445002 137 1583 694 9e-10 
COEFFS -3. 201421350240707397460937 5e-10 -2.195148359942397488845804198694467e-10 
COEFFS -4.486840528746445973609011254303865e-ll 6.088106779527743036338532078059797e-ll 
COEFFS 1.085330344115694363932982905389227e-10 1 . 4 1 912 91 1 550 9 6358 7 6 60 5 65 9330 4 4 81 03e-l 
COEFFS -7. 9489836934953927993774414062 5e-10 -2. 24659714962854742984863277166158 6e-10 
ChebyModel END 

Note the 12 rows of coefficients (corresponding to the requested 12 time polynomial coefficients) each 
with two columns (corresponding to the 2 frequency polynomial coefficients). 

The polynomial coefficients, cm, approximate the function <f>(t, f)—kf~ 2 where is the pulse phase 
at time t and frequency / and k is a constant computed to remove most of the frequency dependence 
due to interstellar dispersion. Therefore: 



where Tk is the k'th Chebyshev polynomial of the first kind. 

All parameter files that are made using TEMP02 include a set of parameters (TZRMJD, TZRFREQ, 
TZRSITE) that correspond to an imaginary arrival time (for site TZRSITE and observing frequency 
TZRFREQ) that, with the given parameter file, leads to zero residual (i.e., is perfectly predicted by the 
timing model). These parameters are used when producing a predictor to align the prediction to 
the timing model. For pulsars that exhibit a large amount of timing noise the prediction using a simple 
model for the pulsar may not be sufficient. In these cases it is common to "whiten" the timing residuals 
by including, for instance, higher order frequency derivative terms in the parameter file. Such timing 
models are usually unable to predict the pulse phase and frequency in the future. 



n 




(5) 



G. Hobbs: Using the pulsar timing software package, TEMP02 



5 DEVELOPING THE SOFTWARE 

Most users and developers of TEMP02 will never need to modify the main TEMP02 source code. 
However, it is straightforward to improve the functionality of TEMP02 by developing new "plugin inter- 
faces". These can be written in the C or the C++ programming languages and, as demonstrated below, 
simple plugins can be written and installed within minutes. 

The next two sections describe how to write an "output" interface and a "graphical" interface. For 
an "output" interface, the main TEMP02 software is run as usual (i.e., forming barycentric arrival times, 
residuals, carrying out the fit and obtaining post-fit timing residuals), but the interface routines are called 
to display the output. The "graphical" interface provides access to all the main TEMP02 routines and 
provides a flexible manner in which to develop the software. 

5.1 Writing your own plugin interfaces 

5.1.1 Writing a new output format 

The text below provides a template for writing a new output format interface: 

#include <stdio.h> 
#include <stdlib.h> 
#include <string.h> 
#include <math.h> 
#include <tempo2.h> 



extern "C" int tempoOutput ( int argc,char 

{ 

int i; 

printf ( "Pulse frequency = %.10f\n", 

(double ) psr[0] .par am [param_f ] . val [ ] ) ; 
printf ( "Pulse frequency derivative = %. 

(double ) psr [ ] . par am [param_f ] . val [ 1 ] ) ; 
printf ( "Dispersion measure = %.5f\n", 

(double ) psr[0] .par am [param_dm] .val [ ] ) 

for ( i=0 ; i<psr [ ] . nobs ; i++) 
{ 

printf ("Site arrival time %d = %g\n",i, 

(double ) psr [ ] . obsn [ i ] . sat ) ; 
printf ( "Barycentric arrival time %d = %g\n",i, 

(double) psr[0] . obsn [i] .bat) ; 
printf ( "Observing frequency %d = %g\n",i, 

(double) psr [0] . obsn [i] . f req) ; 
printf ( "Post-fit residual %d = %g\n",i, 

(double ) psr[0] . obsn [ i ] . residual ) ; 

} 

} 

After installation (see Section 5.1.3 below) this output plugin (which we assume is called my code) 
is available by running: 

% tempo2 -output mycode -f mypar.par mytim.tim 



*argv [], pulsar *psr,int npsr) 



5f\n", 
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The above code shows the most important parameters required (such as obtaining the timing model 
parameters, number of observations and the residuals). Note that: 

psr[i] . param [param_f ] .val[j] 

contains the j'th time derivative of the frequency parameter (param_f ) for the i'th pulsar. 

psr[i] .obsn[j] .residual 

contains post-fit timing residual corresponding to the j'th observation of the i'th pulsar. 

Table 5 shows the most important variables available for each pulsar. The available timing model 
parameters are listed in Table 6 and their various quantities in Table 7. The variables available for each 
pulsar observation are given in Table 8. 

Table 5 Variables Available for Each Pulsar. 



Type 


Parameter 


Meaning 


int 


nobs 


Number of observations 


int 


fitNfree 


Number of degrees of freedom in fit 


int 


nFit 


Number of points in the fit 


double 


posPulsar[3] 


Three-vector pointing at pulsar 


double 


chisq 


X 2 value from the fit 



Table 6 Common Timing Model Parameters. 



Parameter 


Meaning 


param_ 


_al 


Semi-major axis of orbit 


param_ 


_dec j 


Declination 


param_ 


_dmepoch 


Epoch of dispersion measure measurement 


param_ 


ecc 


Orbital eccentricity 


param_ 


_f 


Pulse frequency 


param_ 


_f inish 


MJD of last observation to be used 


param_ 


_om 


Longitude of periastron 


param_ 


_omdot 


Advance of longitude of periastron 


param_ 


_pb 


Orbital period 


param_ 


_pbdot 


Orbital period decay 


param_ 


_pepoch 


Epoch of pulse frequency measurement 


param_ 


_pmdec 


Epoch of proper motion in declination 


param_ 


_pmra 


Epoch of proper motion in right ascension 


param_ 


_posepoch 


Epoch of position measurement 


param_ 


_px 


Parallax 


param_ 


.raj 


Right ascension 


param_ 


_sini 


Sine of orbital inclination angle 


param_ 


.start 


MJD of first observation to be used 


param_ 


.to 


Epoch of periastron 



5.1.2 Writing a new graphical interface 

Whereas an "output" interface allows the user to change the output display, the graphical interfaces 
allow the user to control all the fitting and processing that TEMP02 carries out. A template for such an 
interface is given below: 

#include <stdio.h> 
#include <string.h> 
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Table 7 Variables Available for Each Pulsar Parameter. 



Type 


Parameter 


Meaning 


char ** 
char ** 
long double* 
long double* 
long double* 
int * 
int * 


label 

shortlabel 
val 
prefit 
err 

fitFlag 
paramSet 


Full description of parameter 

Shortened label for parameter 

Post-fit value of the parameter 

Pre-fit value of the parameter 

Uncertainty on the parameter estimate 

= 1 if the user has requested fitting for this parameter 

= 1 if this parameter is included in the timing model 


Table 8 Variables Available for Each Pulsar Observation. 


Type 


Parameter 


Meaning 


long double 
long double 
long double 
long double 
long double 
double 
double 
double 
char * 
char * 


sat 
bat 
bbat 

prefitResidual 

residual 

freq 

freqSSB 
toaErr 
fname 
telID 


Site arrival time (MJD) 

Infinite frequency Solar System barycentric arrival time (MJD) 
Arrival time at binary barycentre (MJD) 
Pre-fit timing residual (s) 
Post-fit timing residual (s) 
Frequency of observation (MHz) 

Frequency of observation in Solar System barycentric frame (Hz) 
Error on site arrival time (fis) 
Observation identifier 
Telescope identification code 



#include <stdlib.h> 
#include <math.h> 
#include <tempo2.h> 

using namespace std; 

extern "C" int graphicallnterf ace ( int argc, char *argv[], 
pulsar *psr, int *npsr) 

{ 

char parFile [MAX_PSR] [MAX_FILELEN] ; 
char timFile [MAX_PSR] [MAX_FILELEN] ; 
int i; 

double globalParameter ; 

*npsr =1; /* For a graphical interface 

that only shows results for one pulsar */ 
printf ( "Graphical Interface: name\n"); 
printf ( "Author : author\n"); 
printf ("CVS Version: $Revision $\n"); 

printf (" type 'h' for help inf ormation\n" ) ; 

/* Obtain all parameters from the command line */ 
for ( i=2 ; i<argc; i++ ) 
{ 

if (strcmp (argv [i] , "-f")==0) 
{ 

st rcpy (parFile [0] ,argv[++i] ) ; 
strcpy (timFile [0] ,argv[++i] ) ; 
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} 

} 

/* Load the parameters */ 
readParf ile (psr,parFile, timFile, *npsr ) ; 
/* Load the arrival times */ 
readTimfile (psr, timFile, *npsr ) ; 
preProcess (psr, *npsr, argc, argv) ; 

/ * Do two iterations for pre- and post-fit residuals*/ 
for (i=0; i<2; i++) 

{ 

/* Form the barycentric arrival times */ 
formBatsAll (psr, *npsr) ; 

/* Form the residuals */ 
f ormResiduals (psr, *npsr, 1) ; 

/* Do the fitting */ 
if (i==0) doFit (psr , *npsr , ) ; 
/* Display the output */ 

else text Output (psr, *npsr , globalParameter , 0,0,0,""); 

} 

// Can add your code here to display the results 
return 0; 



5.1.3 Installing your plugin 

The plugin can be installed simply with a command such as: 

$ g++ myplug_plug . C -shared -o myplug_$ { LOGIN_ARCH }_plug . t 2 
$ cp myplug_$ { LOGIN_ARCH }_plug . t2 $TEMP02 /plugins 

Note that the environment variable $ { LOGIN_ARCH } must be set to the system architecture. 
6 PUBLISHING RESULTS FROM TEMP02 

When publishing new pulsar parameters obtained with TEMP02 it is essential to describe 1) whether 
a weighted or unweighted fit was carried out, 2) the Solar system ephemeris used and 3) details of 
the clock correction process. To ensure that the fit has converged, the fitting process should have been 
iterated until the pre- and post-fit values are identical. 

It is not common for the main algorithms within TEMP02 to change, but it is possible that errors will 
be found and corrected. Of course, it is also likely that TEMP02 will be developed and enhanced in the 
future. In order to ensure that your published results are reproducible various command line arguments 
can be used: 

$ tempo2 . . . -reminder 

This appends to a file in the local directory (T2 command . dat) a description of the exact set of com- 
mands used when running TEMP02. 

$ tempo2 . . . -alllnfo 
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This provides information on exactly which clock correction files are being applied in the conversion to 
terrestrial time. 

$ tempo2 . . . -displayVersion 

This displays the version number of every algorithm being used within TEMP02. 
7 CONCLUSIONS 

Tempo2 provides a versatile means to use (and develop) pulsar timing algorithms. Tempo2 will con- 
tinue to be developed into the foreseeable future. It is likely that the main TEMP02 algorithms will 
not significantly change until nanosecond timing precision is reached with e.g., the Square Kilometre 
Array or similar future telescopes. However, it is expected that a large number of plugin interfaces are 
developed to enhance the capabilities of TEMP02. In the near future it is likely that such interfaces will 
provide the ability to, e.g., correct for dispersion measure variations, produce a pulsar time-scale and to 
allow spacecraft to navigate using pulsar observations. 
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